package net.wanderinghorse.jsonmessage;

import net.wanderinghorse.json.JSONException;
import net.wanderinghorse.json.JSONObject;

/**
 * This class represents an in-bound JSONMessage request,
 * as defined by the JSONMessage framework. See the project
 * home page for full details about the conventions.
 *
 * This class is intended to be only a container for Request data.
 * Actual posting of a request is delegated to the RequestPoster
 * API. (This is different from the JavaScript API, where the
 * Request class has a post() member.)
 *
 * In practice, on the server-side Requests are not polymorphic.
 * That is, all instances tend to be of the same concrete type.
 * The data inside the requests determines which (polymorphic)
 * response class should be used to answer the request.
 *
 * On the client side, Requests tend to (but need not) be polymorphic,
 * whereas client-side Response handlers are almost always
 * non-polymorphic (or monomorphic, if you prefer), but instead
 * simulate polymorphism via a response-handling callback function.
 *
 * The original intent of this class was to act as a native representation
 * of in-bound JSON-formatted messages. However, since Java can
 * be used in both client and server contexts with equal ease
 * (or difficulty, depending on your point of view), the Java-side
 * implementation of this class could also fill the same role
 * as the JSONMessage.Request class from the client-side JavaScript
 * API. That is, it could be used for sending requests to other
 * JSONMessage-style back-ends (or to the same application it is
 * running in).
 */
public class Request extends JSONMessage
{
    private static final long serialVersionUID = 1L;
    /**
     * The key used by HTTP GET/POST requests when sending
     * a JSON-ized request. This key MUST be the same as
     * the JavaScript-side JSONMessage.Request.options.requestKey
     * or the dispatcher won't be able to extract inbound
     * requests.
     */
    public static final String REQUEST_KEY = "JSONRequest";
    /**
     * TODO: implement this!
     *
     * The GET/POST parameter key which specifies a JSONP
     * wrapper name. Request dispatchers should honor this key
     * and generate JSONP output if requested.
     */
    //public static final String JSONP_KEY = "jsonpCallback";
    /**
     * This holds the key used for the framework-conventional
     * outer-most wrapper object for JSON-formatted messages.
     * It is not used as any sort of lookup key, so it can
     * essentially be any arbitrary non-empty string. It is
     * primarily used for informational purposes only.
     */
    private final static String DefaultWrapperName = "JSONMessage.Request";


    /**
     * Initializes this object as per the JSONMessage,
     * plus sets up a different default wrapper name.
     */
    public Request()
    {
        super();
        this.setWrapperName(DefaultWrapperName);
    }

    /**
     * Functionality identical to JSONMessage(String).
     * @param json Message-formatted JSON data.
     * @throws net.wanderinghorse.json.JSONException If JSON parsing fails.
     */
    public Request(String json) throws JSONException
    {
        super(json);
    }

    /**
     * Functionality identical to JSONMessage(JSONObject).
     * @param json Message-formatted JSON data.
     * @throws net.wanderinghorse.json.JSONException If the parent class' ctor throws..
     */
    public Request(JSONObject json) throws JSONException
    {
        super(json);
    }

    /**
     * Semantically equivalent to (JSONMessage.getConfig().optJSONObject("Request")).
     *
     * @return The shared Request class configuration object, or null if it cannot
     * be loaded.
     */
    public static JSONObject getConfig() {
        JSONObject c = JSONMessage.getConfig();
        if( null == c ) return null;
        return c.optJSONObject("Request");
    }

}
